docs(runtime): give the retention witness its section, and take back the comment that outlived its method - #335

Closes #334 — the remainder carved out when PR #280 was closed as superseded. Independent of #333: different branch, no shared files, mergeable in any order.

Dominators.cs is not restored, per the issue.

Что и зачем

0753a45 приземлил свидетеля «minus the dominator tree» — решение осознанное и записанное в csproj. Но три вещи остались висеть: <summary> про доминаторы пережил свой метод и стал документацией к Dispose(); RetentionPath оказался единственным из четырёх runtime-инструментов без секции в README, хотя таблица его возможность обещает; и указатель «See the README» вёл в пустоту. Здесь всё три закрыты, кода не возвращено.

1. A doc comment outlived its method

The extraction removed the method and kept its <summary>, which C# then binds to the next member regardless of the blank line:

/// <summary>
/// The dominator tree of the whole live graph, with retained sizes. …
/// </summary>

public void Dispose()

So the file advertised, on Dispose(), precisely the capability the extraction had removed. Deleted.

2. RetentionPath had no README section

It was the only one of the four runtime tools without one, while README.md:27 kept advertising "Heap analysis (retained, duplicates, retention paths) — ClrMD" in the stack table:

The new section covers what the two verbs answer and why the order matters — census first, because ClrHeap.EnumerateObjects() returns uncollected garbage too and a big heap is not evidence of a leak; then roots, with the field names that turn "this object is alive" into "this field is holding it".

Deliberately weighted toward the parts that constrain trust rather than advertise:

• percentages are shares of the resolved sample, never of the population;
• the verdict is computed over every instance, so no display budget (--sample, --max-hops) can move the diagnosis or the exit code;
• a [stack] root is liveness, not retention;
• the type matcher refuses System.Func<…GTDGoody…> because it once confidently reported a 2-hop path to the wrong object;
• attaching suspends the target — on a multi-GB heap, take a dump.

Plus the exit-code table and why exit 2 is a tier of its own, cross-linked to docs/runtime-witness-operations.md.

Layout and Status were missing the tool too; both now name it, and Status records the dominator tree under Deferred instead of leaving it unmentioned.

3. The dangling pointer

Heap.cs:34 said "See the README" about the dominator tree and the README had nothing to see. It now points at a section that exists, states plainly that dominance is not implemented here, and sends anyone wanting the reasoning to #334, where the extracted implementation's argument is recorded.

Одна поправка к самому #334

Issue поместил dangling pointer в Program.cs. Он в Heap.cs:34. Program.cs тоже упоминает dominator tree, но как ремарку без перекрёстной ссылки, поэтому править там нечего. Записываю, потому что issue писал я, и ошибка в нём — моя.

Тип изменения

• docs — документация
• fix — исправление бага (осиротевший XML-комментарий документировал не тот член)

Как проверено

• dotnet build audit/runtime/RetentionPath -c Release → 0 warnings, 0 errors
• RetentionPath selftest → 16/16
• python audit/runtime/ingest.py --selftest → 26/26
• python tests/run_tests.py → exit 0, wpf 28/28
• проверил программно, что у всех четырёх runtime-инструментов теперь есть секция в README, и что Dominators.cs не вернулся

Связанные issue

Closes #334. Refs #280 (closed as superseded), #309, 0753a45.

Чеклист

• изменение покрыто существующими селфтестами (правка документационная; удаление комментария проверено сборкой)
• README/docs обновлены — в этом и состоит изменение
• коммит в conventional-commit стиле

Generated by Claude Code

Summary by CodeRabbit

• Documentation
  • Added documentation for the runtime retention witness and its census and roots commands.
  • Explained retained versus uncollected heap results, sampled root-path reporting, type matching, attach behavior, exit codes, and runtime.json integration.
  • Updated status information to mark retention analysis as complete and dominator-tree analysis as deferred.
  • Clarified current limitations in retention-path tooling.